Locators with Python are used in Selenium WebDriver to identify and interact with specific web elements on a web page. Before Selenium can click a button, enter text into an input field, select a checkbox, read text, or perform another action, it must first locate the required element in the DOM.
In Python Selenium automation, locators are commonly used with the find_element() and find_elements() methods. Selenium provides traditional locator strategies such as ID, Name, Class Name, Tag Name, Link Text, Partial Link Text, CSS Selector, and XPath.
Course Resource: Selenium Training at JustAcademy | Register for Course Demo
A locator is a method or strategy used by Selenium WebDriver to identify one or more specific elements in the HTML DOM of a web page.
For example, consider the following HTML:
<input id="username" name="user" type="text">The element can be located using its ID:
driver.find_element(By.ID, "username")Once the element is located, Selenium can perform actions such as:
element.send_keys("testuser")Locators are one of the most important concepts in Selenium automation because every interaction starts by identifying the target element.
Web Page
|
v
HTML DOM
|
v
Locator
|
v
Web Element
|
v
Selenium Action
|
+---- click()
+---- send_keys()
+---- clear()
+---- get_attribute()
+---- text
Selenium Python uses the By class to specify locator strategies.
from selenium.webdriver.common.by import ByA typical locator statement looks like this:
element = driver.find_element(By.ID, "username")Here:
Selenium WebDriver provides eight traditional locator strategies.
| Locator | Python Strategy | Example |
|---|---|---|
| ID | By.ID | By.ID, "username" |
| Name | By.NAME | By.NAME, "email" |
| Class Name | By.CLASS_NAME | By.CLASS_NAME, "login-btn" |
| Tag Name | By.TAG_NAME | By.TAG_NAME, "input" |
| Link Text | By.LINK_TEXT | By.LINK_TEXT, "Login" |
| Partial Link Text | By.PARTIAL_LINK_TEXT | By.PARTIAL_LINK_TEXT, "Log" |
| CSS Selector | By.CSS_SELECTOR | By.CSS_SELECTOR, "#username" |
| XPath | By.XPATH | By.XPATH, "//input[@id='username']" |
These eight traditional strategies are commonly used to identify elements in the DOM.
To understand locators, it is important to understand the basic structure of HTML.
<html>
<body>
<form>
<input id="username" name="username" type="text">
<input id="password" name="password" type="password">
<button id="login">Login</button>
</form>
</body>
</html>
In the above HTML:
The ID locator identifies an element using its HTML id attribute.
<input id="username" type="text">from selenium.webdriver.common.by import By
username = driver.find_element(
By.ID,
"username"
)
username = driver.find_element(By.ID, "username")
username.send_keys("testuser")
An ID is especially useful when it uniquely identifies the required element and remains stable across application changes.
The Name locator identifies an element using its name attribute.
<input name="username" type="text">username = driver.find_element(
By.NAME,
"username"
)
email = driver.find_element(
By.NAME,
"email"
)
email.send_keys("[email protected]")
The Class Name locator identifies an element using its class attribute.
<button class="login-button">
Login
</button>
login_button = driver.find_element(
By.CLASS_NAME,
"login-button"
)
login_button.click()By.CLASS_NAME should be given a single class name, not a compound string containing multiple classes.
For example:
<button class="btn login-button primary">
Login
</button>
Do not write:
driver.find_element(
By.CLASS_NAME,
"btn login-button"
)
Instead, use one class:
driver.find_element(
By.CLASS_NAME,
"login-button"
)
Or use a CSS selector for multiple class conditions:
driver.find_element(
By.CSS_SELECTOR,
".btn.login-button.primary"
)
The Tag Name locator identifies elements based on their HTML tag name.
<input type="text">
<input type="password">
<button>Login</button>
inputs = driver.find_elements(
By.TAG_NAME,
"input"
)
for input_element in inputs:
print(input_element.get_attribute("type"))
buttons = driver.find_elements(
By.TAG_NAME,
"button"
)
for button in buttons:
print(button.text)
Link Text is used to locate an anchor element using its exact visible text.
<a href="/login">Login</a>login_link = driver.find_element(
By.LINK_TEXT,
"Login"
)
login_link.click()
driver.find_element(
By.LINK_TEXT,
"Contact Us"
).click()
Partial Link Text identifies an anchor using a portion of its visible text.
<a href="/courses">
Selenium Python Training
</a>
driver.find_element(
By.PARTIAL_LINK_TEXT,
"Selenium"
).click()
If multiple links match, a singular find_element() call returns the first matching element.
CSS Selector is a powerful locator strategy that uses CSS selector syntax to identify elements.
<input id="username" class="form-control" name="user">driver.find_element(
By.CSS_SELECTOR,
"#username"
)
driver.find_element(
By.CSS_SELECTOR,
".form-control"
)
driver.find_element(
By.CSS_SELECTOR,
"input[name='user']"
)
driver.find_element(
By.CSS_SELECTOR,
"input#username"
)
driver.find_element(
By.CSS_SELECTOR,
"input.form-control"
)
CSS selectors can identify elements based on attributes.
driver.find_element(
By.CSS_SELECTOR,
"input[name='username']"
)
driver.find_element(
By.CSS_SELECTOR,
"input[name*='user']"
)
driver.find_element(
By.CSS_SELECTOR,
"input[name^='user']"
)
driver.find_element(
By.CSS_SELECTOR,
"input[name$='name']"
)
CSS selectors are useful when an element contains multiple classes.
<button class="btn login primary">
Login
</button>
driver.find_element(
By.CSS_SELECTOR,
".btn.login.primary"
)
There should be no spaces between class names when the intention is to match one element that contains all those classes.
<div class="login-form">
<input id="username">
<input id="password">
</div>
driver.find_element(
By.CSS_SELECTOR,
".login-form input#username"
)
driver.find_element(
By.CSS_SELECTOR,
".login-form > input#username"
)
XPath is a powerful locator strategy that can identify elements using their attributes, text, hierarchy, relationships, and other conditions.
driver.find_element(
By.XPATH,
"//input"
)
driver.find_element(
By.XPATH,
"//input[@id='username']"
)
driver.find_element(
By.XPATH,
"//input[@name='username']"
)
Multiple attributes can be combined using the and operator.
driver.find_element(
By.XPATH,
"//input[@type='text' and @name='username']"
)
driver.find_element(
By.XPATH,
"//input[@id='username' or @name='username']"
)
XPath can locate elements according to their visible text.
<button>Login</button>driver.find_element(
By.XPATH,
"//button[text()='Login']"
)
driver.find_element(
By.XPATH,
"//a[text()='Contact Us']"
)
The contains() function is useful when an attribute or text contains a known portion of the desired value.
<button class="btn-login-primary">
Login
</button>
driver.find_element(
By.XPATH,
"//button[contains(@class,'login')]"
)
driver.find_element(
By.XPATH,
"//button[contains(text(),'Login')]"
)
The starts-with() function is useful when an attribute value begins with a known string.
driver.find_element(
By.XPATH,
"//input[starts-with(@id,'user')]"
)
For example, it can match IDs such as:
user123
username
user-field
XPath can locate an element based on its parent.
<div class="login">
<input id="username">
</div>
driver.find_element(
By.XPATH,
"//div[@class='login']/input"
)
driver.find_element(
By.XPATH,
"//form[@id='login-form']/input"
)
This selects an input element inside the specified form.
XPath can use relationships between neighboring elements.
<label>Username</label>
<input id="username">
driver.find_element(
By.XPATH,
"//label[text()='Username']/following-sibling::input"
)
driver.find_element(
By.XPATH,
"//input[@id='username']/parent::*"
)
The parent axis can be useful when the target element is easier to identify through a child element or when the relationship between elements is important.
driver.find_element(
By.XPATH,
"//input[@id='username']/ancestor::form"
)
This can locate an ancestor form element containing the input.
An index can be used when multiple elements match the same XPath.
driver.find_element(
By.XPATH,
"(//input)[1]"
)
Another example:
driver.find_element(
By.XPATH,
"(//button)[2]"
)
Indexes should be used carefully because adding or reordering elements in the UI can change which element is selected.
normalize-space() can help when visible text contains extra spaces or formatting whitespace.
driver.find_element(
By.XPATH,
"//button[normalize-space()='Login']"
)
The find_element() method returns the first matching WebElement found using the supplied locator.
element = driver.find_element(
By.ID,
"username"
)
The find_elements() method returns a list of all matching elements.
elements = driver.find_elements(
By.TAG_NAME,
"input"
)
for element in elements:
print(element.get_attribute("name"))
If no matching elements are found, find_elements() returns an empty list.
| find_element() | find_elements() |
|---|---|
| Returns the first matching element. | Returns all matching elements. |
| Returns a WebElement. | Returns a list of WebElements. |
| Raises NoSuchElementException when no element is found. | Returns an empty list when no elements are found. |
| Useful for a specific target element. | Useful for collections of elements. |
Suppose a page contains several buttons:
<button>Save</button>
<button>Cancel</button>
<button>Submit</button>
All buttons can be located using:
buttons = driver.find_elements(
By.TAG_NAME,
"button"
)
for button in buttons:
print(button.text)
| CSS Selector | XPath |
|---|---|
| Uses CSS selector syntax. | Uses XPath expressions. |
| Useful for IDs, classes, and attributes. | Useful for complex DOM relationships. |
| Supports CSS combinators. | Supports parent, child, ancestor, sibling, and other axes. |
| Compact for many common selectors. | Powerful for complex element relationships. |
| Uses CSS attribute matching syntax. | Supports functions such as contains() and starts-with(). |
A good locator should identify the intended element reliably and remain stable when the application's UI changes.
There is no universal rule that one locator must always be used first. The best choice depends on the application's HTML and the stability of available attributes.
A practical approach is:
Stable Unique ID
↓
Stable Name / Test Attribute
↓
Stable CSS Selector
↓
Simple XPath
↓
Complex XPath when necessary
If an application provides dedicated stable attributes for automation, such attributes can be preferable to fragile selectors based on layout or styling.
Many applications provide custom attributes specifically for testing, such as data-testid, data-test, or similar attributes.
<button data-testid="login-button">
Login
</button>
login_button = driver.find_element(
By.CSS_SELECTOR,
"[data-testid='login-button']"
)
login_button = driver.find_element(
By.XPATH,
"//button[@data-testid='login-button']"
)
Some web applications generate IDs dynamically.
<input id="user_839201">If the numeric portion changes on every page load, directly using the complete ID may make the locator fragile.
driver.find_element(
By.XPATH,
"//input[contains(@id,'user_')]"
)
driver.find_element(
By.CSS_SELECTOR,
"input[id^='user_']"
)
Modern frameworks may generate classes that change frequently.
<button class="button_a8f91 login-button">
Login
</button>
If button_a8f91 changes frequently but login-button remains stable, use the stable class:
driver.find_element(
By.CLASS_NAME,
"login-button"
)
Or:
driver.find_element(
By.CSS_SELECTOR,
"button.login-button"
)
<form id="login-form">
<input id="username" name="username" type="text" placeholder="Username">
<input id="password" name="password" type="password" placeholder="Password">
<button id="login">Login</button>
</form>
username = driver.find_element(
By.ID,
"username"
)
password = driver.find_element(
By.ID,
"password"
)
login = driver.find_element(
By.ID,
"login"
)
username.send_keys("testuser")
password.send_keys("Test@123")
login.click()
<input
type="checkbox"
id="terms"
>
terms = driver.find_element(
By.ID,
"terms"
)
if not terms.is_selected():
terms.click()
<input
type="radio"
name="gender"
value="male"
id="male"
>
<input
type="radio"
name="gender"
value="female"
id="female"
>
male = driver.find_element(
By.ID,
"male"
)
male.click()
<select id="country">
<option value="in">India</option>
<option value="us">United States</option>
</select>
country_element = driver.find_element(
By.ID,
"country"
)
For a standard HTML select element, Selenium's Select class can then be used.
from selenium.webdriver.support.ui import Select
country = Select(
driver.find_element(By.ID, "country")
)
country.select_by_visible_text("India")
<button id="submit">
Submit
</button>
driver.find_element(
By.ID,
"submit"
).click()
driver.find_element(
By.XPATH,
"//button[text()='Submit']"
).click()
driver.find_element(
By.CSS_SELECTOR,
"#submit"
).click()
<a href="/products">
Products
</a>
driver.find_element(
By.LINK_TEXT,
"Products"
).click()
driver.find_element(
By.PARTIAL_LINK_TEXT,
"Prod"
).click()
driver.find_element(
By.CSS_SELECTOR,
"a[href='/products']"
).click()
<table id="users">
<tr>
<td>Manish</td>
<td>QA</td>
</tr>
</table>
table = driver.find_element(
By.ID,
"users"
)
rows = table.find_elements(
By.TAG_NAME,
"tr"
)
for row in rows:
print(row.text)
Selenium also supports finding elements from the context of an already located WebElement.
Sometimes it is easier to first locate a parent element and then search for child elements inside it.
<div id="login-form">
<input name="username">
<input name="password">
</div>
login_form = driver.find_element(
By.ID,
"login-form"
)
inputs = login_form.find_elements(
By.TAG_NAME,
"input"
)
for input_element in inputs:
print(input_element.get_attribute("name"))
Locator chaining means first finding a parent element and then locating a child element within that parent.
parent = driver.find_element(
By.ID,
"login-form"
)
username = parent.find_element(
By.NAME,
"username"
)
username.send_keys("testuser")
Locators are frequently combined with WebDriverWait and expected conditions when elements are loaded dynamically.
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
wait = WebDriverWait(driver, 10)
username = wait.until(
EC.visibility_of_element_located(
(By.ID, "username")
)
)
username.send_keys("testuser")
The locator is still the same; the wait controls when Selenium proceeds to interact with the located element.
login_button = WebDriverWait(
driver,
10
).until(
EC.element_to_be_clickable(
(By.ID, "login")
)
)
login_button.click()
Modern applications may use JavaScript frameworks and dynamically generate or update elements. Therefore, the locator should target a stable property whenever possible.
Dynamic UI
|
+---- IDs may change
+---- Classes may change
+---- Elements may appear later
+---- DOM may refresh
|
v
Choose Stable Locator
|
v
Use Appropriate Wait
|
v
Interact with Element
Modern Selenium also supports relative locator capabilities in Python. Relative locators can identify an element based on its position relative to another element, such as above, below, to the left, to the right, or near another element.
from selenium.webdriver.support.relative_locator import locate_withusername = driver.find_element(
By.ID,
"username"
)
password = driver.find_element(
locate_with(By.TAG_NAME, "input").below(username)
)
Relative locators can be useful when an element has weak identifying attributes but has a reliable spatial relationship to another element.
Known Element
|
+---- above
|
+---- below
|
+---- left
|
+---- right
|
+---- near
|
v
Target Element
Traditional stable IDs, names, CSS selectors, or XPath expressions should still be considered when they provide a clearer and more maintainable identification method.
Before using a locator in a large automation suite, verify that it identifies the intended element.
element = driver.find_element(
By.ID,
"username"
)
print(element.tag_name)
print(element.get_attribute("id"))
print(element.get_attribute("name"))
One useful way to test a locator is to temporarily use find_elements() and inspect how many elements match.
elements = driver.find_elements(
By.CSS_SELECTOR,
".login-button"
)
print("Matching elements:", len(elements))
If the intended locator should identify one unique element but the result contains several elements, the locator may need refinement.
A unique locator identifies exactly one intended element.
element = driver.find_element(
By.ID,
"unique-username"
)
For important interactions such as Login, Checkout, Submit, Delete, or Save, a stable and appropriately specific locator is generally desirable.
An ambiguous locator matches multiple elements.
driver.find_elements(
By.TAG_NAME,
"button"
)
This is not necessarily wrong. It is appropriate when the automation needs a collection of buttons. However, if the test needs one specific button, a more specific locator should usually be used.
Consider an XPath that depends heavily on the complete DOM hierarchy:
//html/body/div[1]/div[2]/div[1]/form/div[2]/inputThis type of locator can become fragile when the page structure changes.
If the target has a stable ID:
//input[@id='username']Or:
driver.find_element(
By.ID,
"username"
)
The second version is concise and directly communicates the locator strategy.
When a locator fails, check the following:
Locator Failure
|
+---- Is URL correct?
|
+---- Is element present?
|
+---- Is locator syntax correct?
|
+---- Is element inside iframe?
|
+---- Is page dynamically loading?
|
+---- Is locator unique?
|
+---- Has DOM changed?
|
+---- Is another element blocking interaction?
|
v
Fix Locator / Synchronization
| Exception | Possible Locator Problem |
|---|---|
| NoSuchElementException | Locator does not identify an available element. |
| InvalidSelectorException | XPath or CSS selector syntax is invalid. |
| TimeoutException | Element did not satisfy the expected condition within the wait. |
| StaleElementReferenceException | Previously located element is no longer attached to the current DOM. |
from selenium import webdriver
from selenium.webdriver.common.by import By
driver = webdriver.Chrome()
try:
driver.get(
"https://www.selenium.dev/selenium/web/web-form.html"
)
text_box = driver.find_element(
By.NAME,
"my-text"
)
text_box.send_keys("Selenium Python")
submit_button = driver.find_element(
By.CSS_SELECTOR,
"button"
)
submit_button.click()
message = driver.find_element(
By.ID,
"message"
)
print("Message:", message.text)
finally:
driver.quit()
from selenium import webdriver
from selenium.webdriver.common.by import By
driver = webdriver.Chrome()
try:
driver.get("https://example.com")
# ID
username = driver.find_element(
By.ID,
"username"
)
# NAME
email = driver.find_element(
By.NAME,
"email"
)
# CLASS NAME
button = driver.find_element(
By.CLASS_NAME,
"submit-button"
)
# TAG NAME
headings = driver.find_elements(
By.TAG_NAME,
"h1"
)
# CSS SELECTOR
password = driver.find_element(
By.CSS_SELECTOR,
"input[type='password']"
)
# XPATH
login = driver.find_element(
By.XPATH,
"//button[text()='Login']"
)
print("Headings:", len(headings))
finally:
driver.quit()
Consider a login page with the following HTML:
<form id="login-form">
<input
id="username"
name="username"
type="text"
placeholder="Username"
>
<input
id="password"
name="password"
type="password"
placeholder="Password"
>
<button
id="login"
class="login-button"
>
Login
</button>
</form>
username = driver.find_element(
By.ID,
"username"
)
username = driver.find_element(
By.NAME,
"username"
)
username = driver.find_element(
By.CSS_SELECTOR,
"input#username"
)
username = driver.find_element(
By.XPATH,
"//input[@id='username']"
)
login_button = driver.find_element(
By.ID,
"login"
)
login_button.click()
Open Login Page
↓
Inspect HTML
↓
Identify Stable Attributes
↓
Create Locators
↓
Find Username
↓
Find Password
↓
Find Login Button
↓
Enter Credentials
↓
Click Login
↓
Validate Dashboard
↓
End Test
In a professional automation framework, locators are commonly stored inside Page Object classes instead of being repeated throughout every test.
from selenium.webdriver.common.by import By
class LoginPage:
USERNAME = (By.ID, "username")
PASSWORD = (By.ID, "password")
LOGIN_BUTTON = (By.ID, "login")
def __init__(self, driver):
self.driver = driver
def enter_username(self, username):
self.driver.find_element(
*self.USERNAME
).send_keys(username)
def enter_password(self, password):
self.driver.find_element(
*self.PASSWORD
).send_keys(password)
def click_login(self):
self.driver.find_element(
*self.LOGIN_BUTTON
).click()
login_page.enter_username("testuser")
login_page.enter_password("Test@123")
login_page.click_login()
selenium_project/
|
+-- pages/
| +-- login_page.py
| +-- home_page.py
| +-- checkout_page.py
|
+-- tests/
| +-- test_login.py
| +-- test_search.py
| +-- test_checkout.py
|
+-- utils/
| +-- helpers.py
|
+-- requirements.txt
The Page Object classes can contain the locators and page actions, while test files contain the test scenarios.
| Strategy | Best Used For | Example |
|---|---|---|
| ID | Stable unique IDs | By.ID, "username" |
| NAME | Stable name attributes | By.NAME, "email" |
| CLASS_NAME | Single stable class | By.CLASS_NAME, "login" |
| TAG_NAME | Finding elements by HTML tag | By.TAG_NAME, "button" |
| LINK_TEXT | Exact visible link text | By.LINK_TEXT, "Login" |
| PARTIAL_LINK_TEXT | Partial visible link text | By.PARTIAL_LINK_TEXT, "Log" |
| CSS_SELECTOR | CSS-based attributes, classes, and relationships | By.CSS_SELECTOR, "#login" |
| XPath | Complex attributes, text, and DOM relationships | By.XPATH, "//button[@id='login']" |
A locator is a strategy used to identify a specific web element or group of elements in the DOM.
Selenium provides eight traditional locator strategies: ID, Name, Class Name, Tag Name, Link Text, Partial Link Text, CSS Selector, and XPath.
By is the Selenium Python class used to specify the locator strategy when finding elements.
driver.find_element(
By.ID,
"username"
)
find_element() returns the first matching element, while find_elements() returns a list of matching elements.
It raises a NoSuchElementException.
It returns an empty list.
CSS Selector uses CSS selector syntax, while XPath uses XPath expressions and can represent complex DOM relationships and conditions.
Yes.
driver.find_element(
By.XPATH,
"//button[text()='Login']"
)
A dynamic locator is a locator designed to identify an element even when some parts of its attributes or DOM representation change between executions.
A stable locator relies on an attribute or relationship that is expected to remain consistent across application changes.
Yes. Use find_elements().
Yes. A located WebElement can be used as the search context for another find_element() or find_elements() call.
Absolute XPath depends heavily on the complete DOM hierarchy and can become fragile when the page structure changes.
A test attribute is an HTML attribute intentionally provided to make automated element identification more stable, such as data-testid.
| Concept | Syntax |
|---|---|
| Import By | from selenium.webdriver.common.by import By |
| ID | By.ID, "username" |
| Name | By.NAME, "username" |
| Class | By.CLASS_NAME, "login" |
| Tag | By.TAG_NAME, "button" |
| Link Text | By.LINK_TEXT, "Login" |
| Partial Link Text | By.PARTIAL_LINK_TEXT, "Log" |
| CSS | By.CSS_SELECTOR, "#username" |
| XPath | By.XPATH, "//input[@id='username']" |
| One Element | driver.find_element() |
| Multiple Elements | driver.find_elements() |
| Text XPath | //button[text()='Login'] |
| Contains XPath | //button[contains(text(),'Login')] |
| CSS Attribute | input[name='username'] |
| Relative Locator | locate_with(...) |
HTML Basics
↓
DOM Understanding
↓
By Class
↓
ID Locator
↓
Name Locator
↓
Class Name
↓
Tag Name
↓
Link Text
↓
Partial Link Text
↓
CSS Selector
↓
XPath
↓
find_element()
↓
find_elements()
↓
Dynamic Locators
↓
Explicit Wait + Locators
↓
Relative Locators
↓
Page Object Model
↓
Real-World Automation
Create a Selenium Python script that opens a test website and performs the following tasks:
Locators with Python are the foundation of Selenium WebDriver element interaction. Selenium first identifies an element using a locator and then performs an action on the returned WebElement.
The major traditional locator strategies are ID, Name, Class Name, Tag Name, Link Text, Partial Link Text, CSS Selector, and XPath. Selenium Python also supports relative locator capabilities.
For reliable automation, choose locators based on stable application attributes, avoid unnecessarily fragile selectors, use appropriate waits for dynamic content, and keep locators organized in Page Object classes in larger frameworks.
Selenium Training: https://www.justacademy.co/course-detail/selenium-training
Register for Course Demo: https://www.justacademy.co/register-for-course-demo
Official Selenium Website: https://www.selenium.dev/
